---
title: Advanced Recipes
sidebar_position: 2
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import { FixedSizeExample } from '../../src/components/examples/FixedSizeExample';
import { DefaultCoordinatesExample } from '../../src/components/examples/DefaultCoordinatesExample';
import { FillingCropperExample } from '../../src/components/examples/FillingCropperExample';
import { DefaultVisibleArea } from '../../src/components/examples/DefaultVisibleArea';
import { TransformImageExample } from '../../src/components/examples/TransformImageExample';
import { RotateImageExample } from '../../src/components/examples/RotateImageExample';
import { AdjustStencilExample } from '../../src/components/examples/AdjustStencilExample';
import { ImageRestrictionExample } from '../../src/components/examples/ImageRestrictionExample';
import { SetCoordinatesExample } from '../../src/components/examples/SetCoordinatesExample';
import { CustomRestrictionsExample } from '../../src/components/examples/CustomRestrictionsExample';
import { RefreshExample } from '../../src/components/examples/RefreshExample';
import { CropperScrollExample } from '../../src/components/examples/CropperScrollExample';
import { DefaultTransformsExample } from '../../src/components/examples/DefaultTransformsExample';

# Advanced Recipes


## Fixed stencil

There is the example of a fixed stencil below, that may be useful for mobile devices.
<FixedSizeExample/>

```tsx
import { FixedCropper, ImageRestriction } from 'react-advanced-cropper';
```
```tsx
<FixedCropper
	src={'https://images.pexels.com/photos/5006465/pexels-photo-5006465.jpeg?auto=compress&cs=tinysrgb&h=750&w=1260'}
	stencilSize={{
		width: 300,
		height: 300
	}}
	stencilProps={{
		handlers: false,
		lines: false,
		movable: false,
		resizable: false
	}}
	imageRestriction={ImageRestriction.stencil}
/>
```

## Default Coordinates

Sometimes you should set the default position and default size of the cropped area. For example, if you automatically detect an user face.
It can be achieved by using `defaultSize` and `defaultPosition` props.

<DefaultCoordinatesExample/>


<Tabs>
<TabItem value="function" label="Function">

```tsx
import React from 'react';
import { Cropper, CropperState, CoreSettings } from 'react-advanced-cropper';

export const Example = () => {
	const defaultCoordinates = (state: CropperState, settings: CoreSettings) => {
			return {
				left: 100,
				top: 100,
				width: 400,
				height: 400,
			};
	};
	return (
		<Cropper
			src={'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80'}
			defaultCoordinates={defaultCoordinates}
		/>;
	)
};
```

</TabItem>

<TabItem value="object" label="Object" default>

```tsx
import React from 'react';
import { Cropper } from 'react-advanced-cropper';

export const Example = () => {
	return (
		<Cropper
			src={'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80'}
			defaultCoordinates={{
					left: 100,
					top: 100,
					width: 400,
					height: 400,
			}}
		/>;
	)
};
```

</TabItem>
</Tabs>


### Position / Size

There are situations, when you need set either position or size. In this case `defaultSize` and `defaultPosition` can
be very helpful. You can pass the objects or functions to them alike.



<Tabs>
<TabItem value="position" label="Default Position" default>

```tsx
import React from 'react';
import { Cropper } from 'react-advanced-cropper';

export const Example = () => {
	return (
		<Cropper
			src={'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80'}
			defaultPosition={{
					left: 100,
					top: 100,
			}}
		/>;
	)
};
```

</TabItem>
<TabItem value="size" label="Default Size">

```tsx
import React from 'react';
import { Cropper } from 'react-advanced-cropper';

export const Example = () => {
	return (
		<Cropper
			src={'https://images.unsplash.com/photo-1599140849279-1014532882fe?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1300&q=80'}
			defaultSize={{
					width: 100,
					height: 100,
			}}
		/>;
	)
};
```

</TabItem>
</Tabs>

### Fill the image

The `defaultSize` prop can determine the default size based on the `state`  as mentioned in [its documentation](/docs/components/Cropper#defaultsize).

It can be used to force the cropper fills all visible area by default:

```jsx
import React from 'react';
import { Cropper } from 'react-advanced-cropper';

export const Example = () => {
	const defaultSize = ({ imageSize, visibleArea }) => {
			return {
				width: (visibleArea || imageSize).width,
				height: (visibleArea || imageSize).height,
			};
	}
	return (
		<Cropper
			src={'https://images.pexels.com/photos/6524107/pexels-photo-6524107.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940'}
			defaultSize={defaultSize}
		/>;
	)
};
```

<FillingCropperExample/>



## Default visible area

Moreover, there are situations where you need to save, for example, previous visible area position, i.e. zoom or translate image.
To implement it you can use `defaultVisibleArea` prop.

It should be noted, that visible area can be calculated either before default
coordinates calculation or after one's calculation. The priority is set by
prop [priority](/docs/components/Cropper#priority) that can be either `Priority.coordinates` (default) or `Priority.visibleArea`.

:::tip
If you define only the visible area coordinates it may be easier to set priority to `Priority.visibleArea`. It eliminates the necessity
to set default coordinates by yourself. Default algorithms will handle this situation instead.
:::

<DefaultVisibleArea/>

```jsx
import React from 'react';
import { Cropper, Priority } from 'react-advanced-cropper';

export const Example = () => {
	const defaultVisibleArea = {
		width: 800,
		height: 775,
		left: 63,
		top: 668,
	};
	return (
		<Cropper
			src={
				'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'
			}
			defaultVisibleArea={defaultVisibleArea}
			priority={Priority.visibleArea}
		/>
	);
};
```

## Move and scale image

The cropper has two methods for move and scale image: [`moveImage`](/docs/components/Cropper#methods) and [`zoomImage`](/docs/components/Cropper#methods).

<TransformImageExample/>

The minimal working example:
```jsx
import React from 'react';
import { Cropper, CropperRef } from 'react-advanced-cropper';

export const Example = () => {
	const cropperRef = useRef<CropperRef>(null);
	const zoom = () => {
		if (cropperRef.current) {
			cropperRef.current.zoomImage(2); // zoom-in 2x
		}
	};
	const move = () => {
		if (cropperRef.current) {
			cropperRef.current.moveImage(50, 100); // move x = 50, y = 100
		}
	};
	return (
		<Cropper
			ref={cropperRef}
			src={
				'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'
			}
		/>
	);
};
```

## Rotate / flip image

To rotate image use [`rotateImage`](/docs/components/Cropper#methods) method, it accepts two argument: `rotate` and `options`. They are described
in the method documentation, but in the most cases you should pass only the desired rotate angle to first one as a number (in degrees).
:::warning Available Angles
It's strongly recommended to use an angle multiple of 90. Otherwise, the different restrictions may be broken.
:::

To flip an image use `flip` method, it accepts the three arguments: `horizontal`, `vertical` and `options`. If first is equal to `true`
then image will be flipped horizontally, if the second is equal to `true` then image will be flipped vertically and etc.

<RotateImageExample/>


The minimal working example:
```jsx
import React from 'react';
import { Cropper, CropperRef } from 'react-advanced-cropper';

export const Example = () => {
	const cropperRef = useRef<CropperRef>(null);
	const flip = (horizontal: boolean, vertical: boolean) => {
		if (cropperRef.current) {
			cropperRef.current.flip(horizontal, vertical);
		}
	};
	const rotate = (angle: number) => {
		if (cropperRef.current) {
			cropperRef.current.rotate(angle);
		}
	};
	return (
		<Cropper
			ref={cropperRef}
			src={
				'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'
			}
		/>
	);
};
```

## Adjust Stencil

Adjust stencil is the one of [`transformImage`](/docs/components/Cropper#transformImage) prop option.
By default it's enabled. It makes cropper more convenient especially when you have the limitations of width / height.

Try to resize image when `adjustStencil` is disabled and enabled to feel the difference.

<AdjustStencilExample/>


## Set coordinates

Usually an user changes the coordinates of a stencil, but sometimes you need to set its coordinates programmatically. There is the special method to do it: [setCoordinates](/components/cropper.html#setcoordinates-transform). It applies your changes respect to existing limitation (aspect ratios, minimum size and etc.)

<SetCoordinatesExample/>

The minimal working example:


```jsx
import React from 'react';
import { Cropper, CropperRef } from 'react-advanced-cropper';

export const Example = () => {
	const cropperRef = useRef<CropperRef>(null);

	const resize(width, height, left, top) => {
		if (cropperRef.current) {
			cropperRef.current.setCoordinates({
				width: width,
				height: height,
				left: left,
				top: top
			})
		}
	};

	return (
		<Cropper
			ref={cropperRef}
			src={
				'https://images.unsplash.com/photo-1602718571797-49d5e9d54563?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyNTgzfQ&auto=format&fit=crop&w=1024&q=80'
			}
		/>
	);
};
```

## Different image restrictions

You are able to set different the restrictions of an image position by passing the following string to the `imageRestriction` prop:
- `fillArea` fill area by image and prevents resizing and moving the image beyond the area
- `fitArea` fit image to area and prevents resizing and moving the image beyond the area as much as possible
- `stencil` prevents resizing and moving the image beyond the stencil
- `none` allows free resizing and moving the image

If you use TypeScript, you should use the corresponding enum value.
```tsx
import { ImageRestriction } from 'react-advanced-cropper';
```
```tsx
<Cropper imageRestriction={ImageRestriction.fillArea} />
```

<ImageRestrictionExample/>


## Custom size restrictions

There may be situations, when you need to set the minimum and maximum sizes, for example, in percents, not in pixels. In that situations you should redefine the `sizeRestrictions` functions by passing your custom function as [a corresponding prop](/components/cropper.html#sizeretrictions)

<CustomRestrictionsExample/>

```js
import React from 'react';
import { Cropper, CropperRef, DefaultSettings } from 'react-advanced-cropper';
import { getTransformedImageSize, retrieveSizeRestrictions } from 'advanced-cropper';

export const Example = () => {
	const percentsRestriction = (state: CropperState, settings: DefaultSettings) => {
		const { minWidth, minHeight, maxWidth, maxHeight } = retrieveSizeRestrictions(settings);

		const imageSize = getTransformedImageSize(state);

		return {
			minWidth: (minWidth / 100) * imageSize.width,
			minHeight: (minHeight / 100) * imageSize.height,
			maxWidth: (maxWidth / 100) * imageSize.width,
			maxHeight: (maxHeight / 100) * imageSize.height,
		};
	};

	return (
		<Cropper
			sizeRestrictions={percentsRestriction}
			src={'https://images.unsplash.com/photo-1494205577727-d32e58564756?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=750&q=80'}
		/>
	);
};
```

## Default transforms

There are situations when you need to save the image transforms. In this case `defaultTransforms` can be useful.

It can be either a function or an object.

<DefaultTransformsExample/>

```tsx
import React from 'react';
import { Cropper, CropperRef, retrieveSizeRestrictions, getTransformedImageSize } from 'react-advanced-cropper';

export const Example = () => {
	const defaultTransforms = {
		rotate: 90,
		flip: {
			horizontal: false,
			vertical: false,
		}
	};

	return (
		<Cropper
			defaultTransforms={defaultTransforms}
			src={'https://images.pexels.com/photos/1758144/pexels-photo-1758144.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940'}
		/>
	);
};
```

## Dynamic cropper size

There are situations, when a cropper container size is changed. It's
can't be handle by cropper itself, because it doesn't know about this changes at all (in contradistinction to window's resize),
so you should call [refresh](/components/cropper.html#refresh) method.

:::tip
This situation may seems unlikely, but in fact if your cropper was in a container that was, for example, hidden by
`display: none`, you should call `refresh` method after its appearing.
:::

There is a minimal example:
```html
<Cropper ref={cropperRef}/>
```

```js
// On some change, that causes container's size change
cropperRef.current.refresh();
```


<RefreshExample/>

## Scroll the cropper

Sometimes, there are situations, where an user can scroll the page and accidentally stops the scrolling when cursor happens to be placed on the cropper.
This default behavior is the result of preventing all default mouse and touch events in the cropper background wrapper.

However, this behavior can be easily redefined by replacing the default `CropperBackgroundWrapper` by the custom one.

The source code of this example is available in [the sandbox](https://codesandbox.io/s/react-advanced-cropper-custom-scroll-eyidfn?file=/src/index.tsx).
<CropperScrollExample/>
